/** 
 * Copyright (C) 2012 Foxit Corporation. 
 * All Rights Reserved.
 *
 * The following code is copyrighted and contains proprietary information and trade secrets of Foxit Corporation. 
 * You can only redistribute files listed below to customers of your application, under a written SDK license agreement with Foxit. 
 * You cannot distribute any part of the SDK to general public, even with a SDK license agreement. 
 * Without SDK license agreement, you cannot redistribute anything.
 * 
 * @file	fgsdp.h
 * @brief	Header file for the FDP module.
 * @details	The FDP module offers:
 *			1. Section Loading function.<br>
 *			2. Load font function.<br>
 *			3. Page Loading function.<br>
 *			4. Page Rendering function.<br>
 *			5. Coordination Conversion.<br>
 *			6. Text Search.<br>
 *			7. Text Information.<br>
 *			8. Action Information.<br>
 *			9. Focus Information.<br>
 *			10. Bookmark Information.<br>
 *			11. Text Selection and Cursor Moving.<br>
 *
 * @note	If you want to purchase Foxit PDF SDK license and use ANY of the following functions, please
 *			request for enabling the modules explicitly. 
 */

/**
 * @addtogroup FGSFDP FDP Fdp
 * @brief Definitions and Methods in this module are included in fgsdp.h.
 */
 
#ifndef __FGSDP__
#define __FGSDP__
  
#include "../rt/fgs.h"

#if defined(__cplusplus)
extern "C" {
#endif

/** 
 * @name FGSDP Base Types
 */
/**@{*/
/** @brief FGSDP module reference type. */
typedef const struct __FGSDPModule * FGSDPModuleRef;

/** @brief FGSDP document reference type. */
typedef const struct __FGSDPDocument * FGSDPDocumentRef;

/** @brief FGSDP section reference type. */
typedef const struct __FGSDPSection * FGSDPSectionRef;

/** @brief FGSDP page reference type. */
typedef const struct __FGSDPPage * FGSDPPageRef;

/** @brief FGSDP render reference type. */
typedef const struct __FGSDPRender * FGSDPRenderRef;

/** @brief FGSDP action reference type. */
typedef const struct __FGSDPAction * FGSDPActionRef;

/** @brief FGSDP bookmark reference type. */
typedef const struct __FGSDPBookMark * FGSDPBookMarkRef;
/** @}*/

/** 
 * @name FGSDP Enumeration Types
 */
/**@{*/
/**
 * @brief Enum definitions for writing-mode.
 */
enum {
	/** Left-to-right, then top-to-bottom. For most languages */
    kFGSDPModeLRTB    = 1,
	/** Top-to-bottom, then right-to-left. For some East Asian writing systems */
    kFGSDPModeTBRL    = 2,
	/** Top-to-bottom, then left-to-right. For Mongolian writing system */
    kFGSDPModeTBLR    = 3
};
/** @brief Alias of enumeration for writing-mode. */
typedef UInt32 FGSDPMode;

add test 

/**
 * @brief Enum definitions for parse-mode.
 */
enum {
	/** Use pagination layout to output contents */
    kFGSDPParseModePagination    = 0x10,
	/** Use online(web page) layout to output contents */
    kFGSDPParseModeOnLine        = 0x20
};
/** @brief Alias of enumeration for parse-mode. */
typedef UInt32 FGSDPParseMode;

/**
 * @brief Enum definitions for render flags.
 */
enum {
	/** Set if using text rendering optimized for LCD display. */
    kFGSDPRenderLCDText          = 0x01,
	/** Set if the device is using BGR LCD stripe. */
    kFGSDPRenderBGRStripe        = 0x02
};
/** @brief Alias of enumeration for render flags. */
typedef UInt32 FGSDPRenderFlag;

/**
 * @brief Enum definitions for action types supported.
 */
enum {
    /** Error destination. */
    kFGSDPDestError              = -1,
	/** No or unsupported destination. */
    kFGSDPDestNone               = 0,
	/** An external URL. */
    kFGSDPDestUrl                = 1,
	/** A page inside the same document. */
    kFGSDPDestPage               = 2,
};
/** @brief Alias of enumeration for action types supported. */
typedef SInt32 FGSDPDestType;
/** @}*/

/**
 * @brief Interface for	Character information.
 */
typedef struct __FGSDPCharInfo {
	/**
	 * Unicode for the character. 0 if not available.
	 * Space and new line characters (U+0020 and U+000A) may be generated
	 * according to the text formatting.
	 */
	UInt32          unicode;
	/** X/Y position for the character origin, in page coordination. */
	CGPoint         origin;
	/**
	 * Bounding box of the character, in page coordination
	 * Maybe an empty box (left == right or top == bottom).
	 */
	CGRect          bbox;
} FGSDPCharInfo;

/**
 * @brief                           Load a font from a file stream.
 *
 * @details                         It must be kept valid until close the document.<br>
 *
 * @param[in] 	fontFileStream		Reference to a file stream.
 *
 * @return Reference to a font.
 */
FGSFontRef FGSDPFontOpenWithFile(FGSFileStreamInRef fontFileStream);

/**
 * @brief                           Load a font from a font file path.
 *
 * @details                         It must be kept valid until close the document.<br>
 *
 * @param[in]   fileName			Font file path.
 *
 * @return Reference to a font.
 */
FGSFontRef FGSDPFontOpenWithFileName(CFStringRef fileName);

/**
 * @brief                           Load a font from font family name.
 *
 * @details                         It must be kept valid until close the document.<br>
 *
 * @param[in] 	familyName			Font family name.
 * @param[in] 	flags				Font style, refers to enum definitions of <b>FGSFontStyle</b>.
 * @param[in] 	charset				Charset of font, refers to enum definitions of <b>FGSCharset</b>.
 *
 * @return Reference to a font.
 */    
FGSFontRef FGSDPFontOpenWithFamilyName(CFStringRef familyName, FGSFontStyle flags, FGSCharset charset);

/**
 * @brief                           Close the font used.
 *
 * @param[in] fontHanle             Reference to a font.
 *
 * @return ::kFGSErrorSuccess means success.<br>
 *         For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSDPFontClose(FGSFontRef fontHandle);

/** 
 * @brief                          Get number of sections in the document.
 *
 * @param[in]  document			   Reference to a FDP document.
 *
 * @return Number of sections.
 */
SInt32 FGSDPSectionGetCount(FGSDPDocumentRef document);

/** 
 * @brief                           Get section handler from section index.
 *
 * @param[in] document              Reference to a FDP document.
 * @param[in] index                 The zero-based section index.
 *
 * @return Reference to a section.
 */
FGSDPSectionRef FGSDPSectionGetByIndex(FGSDPDocumentRef document, UInt32 index);

/** 
 * @brief                           Get section index from section handler.
 *
 * @param[in] document              Reference to a FDP document.
 * @param[in] section               Reference to a section.
 *
 * @return The section index, starting from zero.
 */
SInt32 FGSDPSectionGetIndex(FGSDPDocumentRef document, FGSDPSectionRef section);

/** 
 * @brief                           Start loading a section progressively.
 *
 * @param[in] document              Reference to a FDP document.
 * @param[in] section               Reference to a section.
 * @param[in] pause                 Pointer to a <b>::FGSPause</b> object that can pause the loading process.<br>
 *									This can be <b>NULL</b> if no pausing is needed.
 *
 * @return Reference to a section.
 */
FGSErrorRet FGSDPSectionStartLoading(FGSDPDocumentRef document, FGSDPSectionRef section, FGSPause *pause);

/** 
 * @brief                           Continue loading a section.
 *
 * @param[in] document              Reference to a FDP document.
 * @param[in] section               Reference to a section.
 * @param[in] pause                 Pointer to a <b>::FGSPause</b> object that can pause the loading process.<br>
 *									This can be <b>NULL</b> if no pausing is needed.
 *
 * @return							::kFGSErrorSuccess means success.<br>
 *									For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSDPSectionContinueLoading(FGSDPDocumentRef document, FGSDPSectionRef section, FGSPause *pause);

/**
 * @brief                           Close a section and release all related resources.
 *
 * @param[in] document              Reference to a FDP document.
 * @param[in] section               Reference to a section.
 *
 * @return							::kFGSErrorSuccess means success.<br>
 *									For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSDPSectionClose(FGSDPDocumentRef document, FGSDPSectionRef section);

/**
 * @brief                           Get an estimated section loading progress in percentage.
 *
 * @param[in] document              Reference to a FDP document.
 * @param[in] section               Reference to a section.
 *
 * @return							An integer between 0 and 100 (inclusive) indicating the loading progress.
 */
UInt32 FGSDPSectionGetLoadingProgress(FGSDPDocumentRef document, FGSDPSectionRef section);

/**
 * @brief                           Get number of pages in the section.
 *
 * @param[in] document              Reference to a FDP document.
 * @param[in] section               Reference to a section.
 *
 * @return Page count in this section.
 */
UInt32 FGSDPSectionGetPageCount(FGSDPDocumentRef document, FGSDPSectionRef section);

/**
 * @brief                           Load a page from index in this section
 *
 * @param[in] document              Reference to a FDP document.
 * @param[in] section               Reference to a section.
 * @param[in] index                 Page index, starting from zero.
 *
 * @return Reference to a FDP page.
 */
FGSDPPageRef FGSDPPageLoad(FGSDPDocumentRef document, FGSDPSectionRef section, UInt32 index);

/**
 * @brief                           Close a page and release all related resources
 *
 * @param[in] page                  Reference to a FDP page.
 *
 * @return							::kFGSErrorSuccess means success.<br>
 *									For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSDPPageClose(FGSDPPageRef page);

/**
 * @brief                           Get displayable area (bounding box) of a page.
 *
 * @param[in] page                  Reference to a FDP page.
 *
 * @return A rectangle
 */
CGRect FGSDPPageGetBBox(FGSDPPageRef page);

/**
 * @brief                           Get the page size.
 *
 * @param[in] page                  Reference to a FDP page.
 *
 * @return  The size of the page.
 */
CGSize FGSDPPageGetSize(FGSDPPageRef page);

/**
 * @brief 	Get Page display matrix.
 *
 * @param[in] page			Reference to the page. Returned by ::FGSDPPageLoad function.
 * @param[in] devRect		The rect of device context.
 * @param[in] rotate		Page orientation: 0 (normal), 1 (rotated 90 degrees clockwise),
 *							2 (rotated 180 degrees), 3 (rotated 90 degrees counter-clockwise).
 *
 * @return The result page matrix.
 */
CGAffineTransform FGSDPPageGetMatrix(FGSDPPageRef page, const CGRect *devRect, UInt32 rotate);

/**
 * @brief	Start rendering of a page.
 *
 * @details	Rendering is a progressive process. This function starts the rendering process,<br>
 *			and may return before rendering is finished, if a pause structure is provided.<br>
 *
 *			Application should call FGSDPPageRenderingContinue repeatedly to finish the rendering <br>
 *			when return value is FGSDPPageRenderingContinue.<br>
 *
 *			There can be only one rendering procedure for a page at any time. And rendering<br>
 *			can be started over and over again for the same page. If a page rendering is already<br>
 *			active, starting another one will cancel the previous rendering.<br>
 *
 *			Rendering of a page doesn't draw the page background, therefore, you usually need<br>
 *			to draw the background in the context yourself.
 *
 * @param[in] bitmapContext	Bitmap context, as the rendering device.
 * @param[in] page			Reference to a FDP page. The page has to be parsed first.
 * @param[in] matrix        Matrix of displaying page.
 * @param[in] flags			0 for normal display, or combination of flags ::kFGSDPRenderLCDText and ::kFGSDPRenderBGRStripe
 * @param[in] clip			Pointer to clip rectangle (in DIB device coordinations),<br>
 *							or NULL if no clipping needed.
 * @param[in] pause			Pointer to a <b>::FGSPause</b> structure that can pause the rendering process.<br>
 *                          Can be NULL if no pausing is needed.
 * @param[out] renderer		Pointer to a <b>::FGSDPRenderRef</b> object that receives renderer reference.<br>
 *
 * @return					::kFGSErrorSuccess means success.<br>
 *							For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSDPPageRenderingStart(CGContextRef bitmapContext, FGSDPPageRef page, CGAffineTransform *matrix,
                                     FGSDPRenderFlag flags, const CGRect *clip, FGSPause *pause, FGSDPRenderRef *renderer);

/**
 * @brief 	Continue the page rendering
 *
 * @details	This function may return any time when the pause interface indicates <br>
 *			a pause is needed. Application can call <b>::FGSDPPageRenderingContinue</b> any number<br>
 *			of times, until <b>::kFGSErrorToBecontinued</b> is not returned.
 *
 * @param[in] renderer		Reference to rendering object.
 * @param[in] pause			Pointer to a <b>::FGSPause</b> structure that can pause the rendering process.<br>
 *							Can be NULL if no pausing is needed.
 *
 * @return ::kFGSErrorSuccess means success.<br>
 *         For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSDPPageRenderingContinue(FGSDPRenderRef renderer, FGSPause *pause);

/**
 * @brief 	Stop the page rendering.
 *
 * @details	Release the allocated rendering resource by call <b>::FGSDPPageRenderingStart</b>.
 *
 * @param[in] renderer		Reference to rendering object.
 *
 * @return					::kFGSErrorSuccess means success.<br>
 *							For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSDPPageRenderingStop(FGSDPRenderRef renderer);

/**
 * @brief	Get an estimated rendering progress in percentage
 *
 * @details	Release the allocated rendering resource by call <b>::FGSDPPageRenderingStart</b>.
 *
 * @param[in] renderer		Reference to rendering object.
 *
 * @return					An integer between 0 and 100 (inclusive) indicating the rendering progress.
 */
UInt32 FGSDPPageRenderingGetProgress(FGSDPRenderRef renderer);

/**
 * @brief	Find first occurrence of a pattern string in a page, from a particular position.
 *
 * @details	A page must be parsed first before it can be searched.<br>
 *			There can be only one search in progress for a page. A new search will <br>
 *			cancel the previous one.
 *
 * @param[in] page			Reference to a FDP page.
 * @param[in] pattern		A zero-terminated unicode string to be found. 
 * @param[in] pos			The position, returned from <b>::FGSDPSearchGetRect</b>.
 *							Or 0 from the beginning of page, -1 from the end of page.
 * @param[in] flags			Search flags, it must be ::kFGSMatchCase or ::kFGSMatchWholeWord or ::kFGSMatchConsecutive.
 *
 * @return					::kFGSErrorSuccess means success.<br>
 *							For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSDPSearchStart(FGSDPPageRef page, CFStringRef pattern, SInt32 pos, FGSMathchFlag flags);

/**
 * @brief	Find next occurrence of a search.
 *
 * @details  ::FGSDPSearchStart must be called for this page first.
 *
 * @param[in] page			Reference to a FDP page.
 *
 * @return					::kFGSErrorSuccess means success.<br>
 *							For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSDPSearchNext(FGSDPPageRef page);

/**
 * @brief	Find previous occurrence of a search.
 *
 * @details ::FGSDPSearchStart must be called for this page first.
 *
 * @param[in] page			Reference to a FDP page.
 *
 * @return					::kFGSErrorSuccess means success.<br>
 *							For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSDPSearchPrev(FGSDPPageRef page);

/**
 * @brief	Get number of rectangles for last found result.
 *
 * @param[in] page			Reference to a FDP page.
 *
 * @return					The number of found rects.
 */
SInt32 FGSDPSearchCountRects(FGSDPPageRef page);

/**
 * @brief	Get a particular found rectangle
 *
 * @details	Application should always call ::FGSDPSearchCountRects first to get<br>
 *			number of rectangles, then use this function to get each rectangle.<br>
 *			The returned rectangle uses page coordination system.
 *
 * @param[in] page			Reference to a FDP page.
 * @param[in] index			Zero-based index for the rectangle.
 *
 * @return					The result rectangle.
 */
CGRect FGSDPSearchGetRect(FGSDPPageRef page, SInt32 index);

/**
 * @brief	Return position of current search result
 *
 * @param[in] page			Reference to a FDP page.
 *
 * @return					The zero-based character index for the current search result.
 */
SInt32 FGSDPSearchGetCurrentPos(FGSDPPageRef page);

/**
 * @brief	Get count of characters in the page.
 *
 * @param[in] page			Reference to a FDP page.
 *
 * @return					The count of characters in the page.
 */
SInt32 FGSDPTextGetCharCount(FGSDPPageRef page);

/**
 * @brief	Get character information.
 *
 * @details	Application must call ::FGSDPTextGetCharCount first before it can call this function<br>
 *			for any particular characters.
 *
 * @param[in] page			Reference to a FDP page.
 * @param[in] index			Character index, starting from zero.
 * @param[out] charInfo		Pointer to a <b>FGSDPCharInfo</b> struct that receives the character info.
 *
 * @return					::kFGSErrorSuccess means success.<br>
 *							For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSDPTextGetCharInfo(FGSDPPageRef page, SInt32 index, FGSDPCharInfo *charInfo);

/**
 * @brief 	Get index of character exact to a certain position on the page.
 *
 * @details	This function finds the character that's nearest to the particular page position.			
 *
 * @param[in] page			Reference to a FDP page.
 * @param[in] x				X position in ePub page coordination system.
 * @param[in] y				Y position in ePub page coordination system.
 * @param[in] tolerance		Max search radius in ePub page coordination system.
 *
 * @return					An integer receiving zero-based character index.
 */
SInt32 FGSDPTextGetCharIndexAtPos(FGSDPPageRef page, Float32 x, Float32 y, Float32 tolerance);

/**
 * @brief	Get type of an action.
 *
 * @details	Each different type of destination has different data structure.
 *
 * @param[in] document		Reference to a FDP document.
 * @param[in] action		Reference to an action object.
 *
 * @return					The type of the destination, refers to enum definitions of <b>FGSDPDestType</b>.
 */
FGSDPDestType FGSDPActionGetType(FGSDPDocumentRef document, FGSDPActionRef action);

/**
 * @brief 	Get section index of a destination(action) pointing to
 *
 * @param[in] document		Reference to a FDP document.
 * @param[in] action		Reference to an action object.
 *
 * @return					Reference a section.
 */
FGSDPSectionRef FGSDPActionGetSection(FGSDPDocumentRef document, FGSDPActionRef action);

/**
 * @brief 	Get page index in the section of a destination(action) pointing to
 *
 * @details	For <b>::kFGSDPDestPage</b> actions, there is no accurate position saved in them before
 *			the page loaded. So application should firstly get the page index and load page, then call
 *			<b>::FGSDPActionGetPosition</b> to get target position.<br>	
 * 			This function is only for  kFGSDPDestPage action. You should call <b>FGSDPActionGetType</b> firstly to determine<br>
 *			specific type.
 *
 * @param[in] document		Reference to a FDP document.
 * @param[in] action		Reference to an action object.
 * @param[in] section		The section handle, the section must be loaded.
 *
 * @return Page index.
 */
SInt32 FGSDPActionGetPageIndex(FGSDPDocumentRef document, FGSDPActionRef action, FGSDPSectionRef section);

/**
 * @brief	Get position the action pointing to.
 *
 * @details	This function is only for <b>::kFGSDPDestPage</b> actions.You should call <b>FGSDPActionGetType</b> firstly to determine<br>
 *			specific type.
 *
 * @param[in] document		Reference to a FDP document.
 * @param[in] action		Reference to an action object.
 * @param[in] page			Reference to an FDP page.
 *
 * @return					Destination position in ePub page coordination system.
 */
CGPoint FGSDPActionGetPosition(FGSDPDocumentRef document, FGSDPActionRef action, FGSDPPageRef page);

/**
 * @brief	Get Universal Resource Identifier from a action.
 *
 * @details	The buffer is output in Unicode, using UTF-16LE format. It's terminated by
 *			two consecutive zero bytes.<br>
 *			You should always call <b>FGSDPActionGetType</b> firstly to get action type. If the type 
 *			is <b>::kFGSDPDestPageUrl</b>, then you can call this function to get specific URL string.
 *			for this call.
 *
 * @param[in] action		Reference to an action object.
 *
 * @return The action string, user should release the string by calling <b>CFRelease</b>.
 */
CFStringRef FGSDPActionCopyURI(FGSDPActionRef action);

/**
 * @brief	Release a action object.
 *
 * @param[in] action		Reference to an action object.
 *
 * @return ::kFGSErrorSuccess means success.<br>
 *         For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSDPActionRelease(FGSDPActionRef action);

/**
 * @brief	Get data pointing to current reading position.
 *
 * @details	This function retrieves data pointing to given reading position, application
 *			can save it to disk for future use, or convert it to an action by calling
 *			<b>::FGSDPFocusGetAction</b> to navigate to the physical position.
 *
 * @param[in] document		Reference to a FDP document.
 * @param[in] page			Reference to a FDP page.
 * @param[in] x				X position in ePub page coordination system.
 * @param[in] y				Y position in ePub page coordination system.
 * @param[in] fTolerance	Max get radius in ePub page coordination system.
 *
 * @return					The focus data, user should release the string by calling <b>CFRelease</b>.
 */
CFDataRef FGSDPFocusCopyData(FGSDPDocumentRef document, FGSDPPageRef page, Float32 x, Float32 y, Float32 fTolerance);

/**
 * @brief 	Create an action pointing to current reading position
 *
 * @details	This function creates an action from data retrieved from <b>::FGSDPFocusGetData</b>.<br>
 *			With this action, application can navigate to new physical position after adjusting
 *			font size or page size. Note that call <b>::FGSDPActionRelease</b> when the action
 *			is no longer used.
 *
 * @param[in] document		Reference to a FDP document.
 * @param[in] data			Data, the focus get by.
 *
 * @return					Reference to an action object.
 */
FGSDPActionRef FGSDPFocusGetAction(FGSDPDocumentRef document, CFDataRef data);

/**
 * @brief	Get the count of children of a bookmark item
 *
 * @param[in] document		Reference to a FDP document.
 * @param[in] bookmark		Reference to a bookmark, If bookmark is NULL, it returns all root bookmarks.
 *
 * @return Children count.
 */
SInt32 FGSDPBookmarkCountChildren(FGSDPDocumentRef document, FGSDPBookMarkRef bookmark);

/**
 * @brief	Get the index-th child of a bookmark item.
 *
 * @param[in] document		Reference to a FDP document.
 * @param[in] parent		Handle to the parent bookmark. 
 *							Can be NULL if you want to get the first top level item.
 * @param[in] index			The index number in the sub bookmarks.
 *
 * @return					Reference to the first child or top level bookmark item. 
 *							If result is NULL, then bookmark not found.
 */
FGSDPBookMarkRef FGSDPBookmarkGetChild(FGSDPDocumentRef document, FGSDPBookMarkRef parent, SInt32 index);

/**
 * @brief	Get title of a bookmark
 *
 * @details	The title is output in Unicode, using UTF-16LE format. It's terminated by<br>
 *			two consecutive zero bytes.<br>
 *
 * @param[in] document		Reference to a FDP document.
 * @param[in] bookmark		Reference to a bookmark.
 *
 * @return                  The string, user should release the string by calling <b>CFRelease</b>.
 */
CFStringRef FGSDPBookmarkCopyTitle(FGSDPDocumentRef document, FGSDPBookMarkRef bookmark);

/**
 * @brief	Get action(s) associated with a particular bookmark
 *
 * @param[in] document		Reference to a FDP document.
 * @param[in] bookmark		Reference to a bookmark.
 *
 * @return					Reference to the first action.
 */
FGSDPActionRef FGSDPBookmarkGetAction(FGSDPDocumentRef document, FGSDPBookMarkRef bookmark);

/**
 * @brief	Set start position for text selection or cursor moving. 
 *
 * @details	User MUST call this function firstly before they perform other functions of text 
 *			selection or cursor moving.
 *
 * @param[in] page			Reference to a FDP page.
 * @param[in] x				Left pixel position of the display area in the page coordination.
 * @param[in] y				Top pixel position of the display area in the page coordination.
 *
 * @return					::kFGSErrorSuccess means success.<br>
 *							For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSDPTextSelectionSetStartPos(FGSDPPageRef page, Float32 x, Float32 y);

/**
 * @brief	Reset current state and move from start position again
 *
 * @param[in] page			Reference to a FDP page.
 *
 * @return					::kFGSErrorSuccess means success.<br>
 *							For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSDPTextSelectionReset(FGSDPPageRef page);

/**
 * @brief	Get actual position of start character
 *
 * @param[in] page			Reference to a FDP page.
 *
 * @return					Position of the display area in the page coordination.
 */
CGPoint FGSDPTextSelectionGetStartPos(FGSDPPageRef page);

/**
 * @brief	Get the position of current character
 *
 * @param[in] page			Reference to a FDP page.
 *
 * @return					Pixel position of the display area in the page coordination.
 */
CGPoint FGSDPTextSelectionGetCurPos(FGSDPPageRef page);

/**
 * @brief	Select a whole word at start position
 *
 * @param[in] page			Reference to a FDP page.
 *
 * @return					::kFGSErrorSuccess means success.<br>
 *							For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSDPTextSelectionSelectWord(FGSDPPageRef page);

/**
 * @brief	Select text in the range of given rectangle
 *
 * @param[in] page			Reference to a FDP page.
 * @param[in] pos			The end pixel position of the display area in the page coordination.
 *
 * @return					::kFGSErrorSuccess means success.<br>
 *							For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 * @note                    The start pixel position of the display area is confirmed by ::FGSDPTextSelectionSetStartPos.
 */
FGSErrorRet FGSDPTextSelectionSelectRectEndPos(FGSDPPageRef page, CGPoint pos);

/**
 * @brief	Select text in the range of paragraph
 *
 * @param[in] page			Reference to a FDP page.
 * @param[in] pos			The end pixel position of the display area in the page coordination.
 *
 * @return					::kFGSErrorSuccess means success.<br>
 *							For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 * @note                    The start pixel position of the display area is confirmed by ::FGSDPTextSelectionSetStartPos.
 */
FGSErrorRet FGSDPTextSelectionSelectParagraphEndPos(FGSDPPageRef page, CGPoint pos);

/**
 * @brief	Move to next character, and select it
 *
 * @param[in] page			Reference to a FDP page.
 *
 * @return					::kFGSErrorSuccess means success.<br>
 *							For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSDPTextSelectionNextChar(FGSDPPageRef page);

/**
 * @brief	Move to previous character, and select it
 *
 * @param[in] page			Reference to a FDP page.
 *
 * @return					::kFGSErrorSuccess means success.<br>
 *							For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSDPTextSelectionPrevChar(FGSDPPageRef page);

/**
 * @brief	Move to next word, and select it.
 *
 * @param[in] page			Reference to a FDP page.
 *
 * @return					::kFGSErrorSuccess means success.<br>
 *							For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSDPTextSelectionNextWord(FGSDPPageRef page);

/**
 * @brief	Move to previous word, and select it
 *
 * @param[in] page			Reference to a FDP page.
 *
 * @return					::kFGSErrorSuccess means success.<br>
 *							For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSDPTextSelectionPrevWord(FGSDPPageRef page);

/**
 * @brief	Get number of rectangles for text selection.
 *
 * @details	Application should always call <b>::FGSDPTextSelectionCountRects</b> first to get<br>
 *			number of rectangles, then use <b>::FGSDPTextSelectionGetRect</b> to get each rectangle.<br>
 *			The returned rectangle uses page coordination system.
 *
 * @param[in] page			Reference to a FDP page.
 *
 * @return                  Actual rectangle counts. or zero for failure.
 */
SInt32 FGSDPTextSelectionCountRects(FGSDPPageRef page);

/**
 * @brief	Get rectangle information of current text selection.
 *
 * @param[in] page			Reference to a FDP page.
 * @param[in] index			The zero-based index for the rectangle.
 *
 * @return                  The result rectangle.
 */
CGRect FGSDPTextSelectionGetRect(FGSDPPageRef page, SInt32 index);

#if defined(__cplusplus)
}
#endif

#endif// __FGSDP__

/** @} */
